docs(skills): carry the deciding question in the App / Platform Boundary - #15625

Fixes #15428

What changed

One bullet added to skills/objectstack-platform/SKILL.md, section The App / Platform Boundary, directly after the bullet that states the conclusion. One file, one hunk, +6 lines, 0 deletions. No other file, no other section, no other skill; nothing under this skill's references/ or rules/.

Before — the section stated the conclusion, but not the test that produces it, so an app author had to already know the answer to apply it:

- **Business features belong in the app; capability belongs in the platform.**
  A missing default, a wrong diagnostic, a shape the spec refuses — the fix is
  upstream. Raise it there; do not compensate for it here.
- **A platform defect means waiting for the platform fix.** No defensive coding,
  …

After — the discriminator sits next to the conclusion it produces:

- **Business features belong in the app; capability belongs in the platform.**
  A missing default, a wrong diagnostic, a shape the spec refuses — the fix is
  upstream. Raise it there; do not compensate for it here.
- **Could this be written by something that has only the metadata, and no
  knowledge of this company?** *No* — it encodes this company's own judgement (a
  discount ceiling, who a case is assigned to, how won/lost is booked) ⇒ the
  app. *Yes* — it only asks whether the metadata is self-consistent (reference
  integrity, translation coverage, view rosters, sharing-rule coverage, CRUD
  round-trips, RLS probes per declared position) ⇒ the platform.
- **A platform defect means waiting for the platform fix.** No defensive coding,
  …

Budget — measured on this tree, no ceiling raise

node scripts/check-skills-token-ratchet.mjs, the gate's own line, verbatim.

Before, on origin/main 6b8c67778:

✓ check-skills-token-ratchet: skills/objectstack-platform/SKILL.md is 12868 tokens (ceiling 12984; headroom 116).

After, on eb39034d7:

✓ check-skills-token-ratchet: skills/objectstack-platform/SKILL.md is 12983 tokens (ceiling 12984; headroom 1).
✓ check-skills-token-ratchet: 36 authored bundle file(s) within their ceilings; 10 generator-owned file(s) measured, not ratcheted.

Both readings the governed skills/** surface owes — lines, and tokens because this surface is priced in tokens:

The package delta reads +116 against the file's +115 because each row is ceil(bytes / 4) computed over its own total; the byte delta is +461 in all three rows, and only this file changed.

Fitting it in the headroom — what was trimmed, and what was not

The gate counts ceil(utf8 bytes / 4), so the headroom is exactly 465 bytes for this file (51471 bytes now, 51936 at the ceiling). The routed suggestion measured 546 bytes. Nothing already in the section was trimmed — no existing doctrine was deleted to buy room, and the ceiling was not touched. Two clauses of the new text were dropped instead:

1. the lead-in label "The deciding question:" (23 bytes) — the bold question is itself the bullet's lead-in, which is the section's house shape;
2. the trailing "do not hand-write it in the app" — the next bullet already carries "no hand-written predicate re-implementing a platform rule" three lines below, so it was a duplicate.

The ruled content ships whole: the question verbatim, both outcomes, and both example lists (a discount ceiling · who a case is assigned to · how won/lost is booked; reference integrity · translation coverage · view rosters · sharing-rule coverage · CRUD round-trips · RLS probes per declared position). The amendment lands at 461 bytes.

Deliberately not in this diff

• No second copy of the doctrine. objectstack-pm-dispatch defers to this section by name and objectstack-upgrade carries a differently-scoped boundary; single-owner is the existing arrangement and a second copy would be a drift site.
• The repo-internal second question does not ship. Whether a second app would copy the implementation decides what a package in this monorepo publishes; an app author cannot act on it.
• Rules only. No provenance narrative, no dated rulings, no issue ids in the published text.
• No changeset — nothing is published from any released package; the skip-changeset label carries that, per the precedent on sibling skill and playbook files.

Gates — 21 derived families, all green at eb39034d7

Family derived on this tree, not recalled: node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (change set read by the script from the merge base — 1 path), harvested with --commands, each run with its exit code captured before any pipe. Every line below is the gate's own verdict.

• node scripts/check-ci-filter-parity.mjs — OK: all 148 declared cross-package glob(s) (102 unique) are covered by core or crosspkg, every crosspkg entry still covers one, and the test job's if: still names both filters.
• node scripts/check-closing-keyword-parity.mjs — check-closing-keyword-parity: OK (3 parsers agree on all 9 keywords and both measured separators; sweep found 5 file(s) carrying the grammar across 7572 tracked file(s), all registered).
• node scripts/check-closing-keyword-parity.mjs --self-test — ✓ 24 assertions, 5 mutations of the shipped parsers each driven to red.
• node scripts/check-comment-mask-corpus.mjs — ✓ comment-mask corpus sweep: 5964 files, 0 disagree, 0 unparseable (comparator self-test: 17 cases pass).
• node scripts/check-skills-token-ratchet.mjs — quoted in full above.
• node scripts/check-skills-token-ratchet.mjs --self-test — ✓ check-skills-token-ratchet self-test: 64 cases pass.
• pnpm --filter @objectstack/lint run check:doc-formula-expressions — ✓ 22 record-scoped formula example(s) across 428 files / 1371 TS blocks judged clean; ✓ 9 spec TSDoc example(s) clean; ✓ 14 field-level predicate(s) clean.
• pnpm --filter @objectstack/spec run check:skill-docs — ✅ Skill docs in sync.
• pnpm check:agent-test-spelling — ✓ 0 violations, 450 file(s) read.
• pnpm check:corpus-claim-drift — check-corpus-claim-drift: OK, no new claim sites beside a pinned spelling.
• pnpm check:cross-package-test-inputs — OK: 27 package(s) read outside themselves, all declared, and turbo.json hashes every declared glob.
• pnpm check:doc-authoring — ✓ doc authoring guard: 46 published skill files clean, no internal issue-id references (plus the spec-string and sibling-prose legs clean).
• pnpm check:driver-memory-census — check-driver-memory-census: OK, every declaration ledgered and every ledger entry live.
• pnpm check:nul-bytes — check-nul-bytes: OK (scanned 7565 text file(s), skipped 7 binary; no raw ASCII control bytes).
• pnpm check:pm-governed-merges — ✓ check-governed-merges --self-test: 263 assertions; live: the real generator declared 9 output(s) and certified this tree.
• pnpm check:refd-timer-probe — OK: 5959 source file(s) swept.
• pnpm check:role-word — check-role-word: OK, no new occurrences of the reserved word.
• pnpm check:skill-compatibility — ✓ 11 SKILL.md file(s) reconciled against 79 workspace packages.
• pnpm check:skill-frame-sync — ✓ 2 copies of the decision frame are structurally isomorphic across 2 files.
• pnpm check:skill-identifier-liveness — OK: Leg 1, 465 citation(s) over 46 published file(s) against 95964 implementation word tokens; Leg 2, 8 registered exhaustive section(s), 0 ledgered gap(s).
• pnpm check:watch-hint-literal — ✓ 58 declaration(s) across 4 rostered name(s), no unrostered spelling in the tree.

check:doc-formula-expressions first exited 3 with PREREQUISITE NOT MET — read as not measured, never as a finding. It named @objectstack/formula, then @objectstack/lint; both were built (through the shared verify lock) and it was re-run green. All three prerequisite-driven runs are reported here rather than dropped.

The whole family was run after the final commit, so every verdict above is a reading of eb39034d7 and not of an earlier tree.

Review route

node scripts/pm/check-governed-merges.mjs --test skills/objectstack-platform/SKILL.md — ⛔ GOVERNED — a human merge is the review record for this PR, exit 3. Draft PR: no ready flip, no merge queue, no auto-merge, no agent approval.

🤖 Generated with Claude Code

Generated by Claude Code

Generated by Claude Code